home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 101-125 / scopedisk102 / kdlib / kd_freq.doc < prev    next >
Text File  |  1995-03-19  |  12KB  |  332 lines
  1. kd_freq.library                                                  Release 1.00
  2. ---------------                                                  ------------
  3.                              By: Khalid Aldoseri
  4.  
  5.  
  6.  
  7. 'kd_freq.library' is a standard Amiga library that has three functions:
  8. FReq(), Path() and PatMatch(). FReq() calls my file requester (FR) so that
  9. any program can use it.  The FR is totally reentrant, and you can have
  10. multiple programs calling it simultaenously.  Path() simply returns
  11. the full path to a file or directory.  PatMatch() implements AmigaDOS style
  12. wildcard pattern matching.
  13.  
  14. To open the library, use OpenLibrary() like any other normal Amiga library.
  15. Look at test.c for the exact opening procedure.  You will need to assemble
  16. and link glue.asm (either manx.glue.asm or lattice.glue.asm) along with your
  17. own object files.
  18.  
  19.   e.g.  for Manx:
  20.  
  21.        cc +l test.c
  22.        as glue.asm
  23.        ln test.o glue.o -lc32
  24.  
  25.  
  26.  
  27.                                   AutoDocs:
  28. ------------------------------------------------------------------------------
  29.  
  30. kd_freq.library/FReq
  31.  
  32. NAME
  33.  
  34.         FReq - bring up a file requester and obtain a file name.
  35.  
  36. SYNOPSIS
  37.  
  38.         result = FReq(screen,reqtitle,filename,directory,pattern,flags,extras);
  39.  
  40.         LONG  result
  41.         struct Screen *screen;
  42.         UBYTE *reqtitle;
  43.         UBYTE *filename;
  44.         UBYTE *directory;
  45.         UBYTE *pattern;
  46.         ULONG flags;
  47.         struct ExtraData *extras;
  48.  
  49.  
  50. FUNCTION
  51.  
  52.         Accepts a default directory name, default file name, and a
  53.         default pattern (standard AmigaDOS wildcard pattern) and returns
  54.         a selected directory, selected file name, and last pattern used
  55.         in the same variables that were used to call the requester.
  56.  
  57.         The 'screen' argument is a pointer to a Screen structure.  This tells
  58.         the file requester to show up on a specific screen.  If you use
  59.         NULL, then the FR will show up on the WorkBench screen.
  60.  
  61.         'reqtitle' is the title that will appear as the title of the file
  62.         requester.
  63.  
  64.         'flags' is a set of flags that control the operation of the FR.
  65.         The flags are the following:
  66.  
  67.             FR_NOINFO       Do not show any file that ends with <.info>.
  68.                             The user can change this setting later by
  69.                             clicking on the 'I' gadget.
  70.  
  71.             FR_NORESIZE     Do not allow the user to resize the FR.
  72.  
  73.             FR_NOTITLEBAR   Do not show the close window gadget, the drag
  74.                             bar, or the front/back gadgets.  The title still
  75.                             gets displayed.  This makes the FR non-movable.
  76.                             This also automatically triggers FR_NORESIZE.
  77.                             If you don't provide a title the file list will
  78.                             resize and fill in the empty space.
  79.  
  80.             FR_AUTOPOSITION Tells the FR to decide where it wants to come up
  81.                             on its own.  (i.e. ignore LeftEdge and TopEdge)
  82.  
  83.             FR_AUTOSIZE     Tells the FR to decide its size on its own.
  84.                             (i.e. ignore Width and Height)
  85.  
  86.             FR_OKTEXT       Tells the FR that we specified an alternate
  87.                             OK text in 'extras.oktext'.
  88.  
  89.             FR_CANCELTEXT   Tells the FR that we specified an alternate
  90.                             'Cancel' text in 'extras.canceltext'.
  91.  
  92.             FR_DUALWILD     When you set this flag, the wildcard pattern
  93.                             you provide in 'pattern' is fixed and is applied
  94.                             to all files in the FR.  The user then gets a
  95.                             second wildcard in the Wildcard gadget.  (this
  96.                             defauls to #?).  In essence, this allows you
  97.                             to specify a pattern that will appply to ALL
  98.                             the FR, no matter what the user selects as a
  99.                             wildcard.  The user's wildcard is applied to
  100.                             a file after it passes from the first wildcard.
  101.  
  102.             FR_FRONTSCREEN  Forces the FR to come up on the front screen.
  103.  
  104.             FR_NOTEXTSHADOW Turns off the text shadowing in all of the FR.
  105.  
  106.             FR_NEWFONT      Tells the FR to use a different font than the
  107.                             standard Topaz 8.  This can be any fixed spacing
  108.                             font from 5 to 16 in size.  NO sanity checking is
  109.                             done on the font size.  It is up to you to see
  110.                             how the font looks like.  The FR will rescale
  111.                             everything to suit the new font.  You need to
  112.                             provide a pointer to a TextFont structure in
  113.                             extras->NewFont.
  114.  
  115.             FR_SCREENFONT   As above, but uses the current font on the screen
  116.                             the FR will show up on.  This always overrides
  117.                             FR_NEWFONT.
  118.  
  119.             FR_REPLACEIMAGES Replaces the standard images in the FR with
  120.                             the users's own.  The ExtraData struct below
  121.                             shows where to place each pointer.  You can
  122.                             use any depth of bitplanes as long as they match
  123.                             the same width/height as the original gadgets.
  124.                             Be creative!  Note that the size of the imagery
  125.                             changes with the requested font size.
  126.  
  127.  
  128.         These flags are defined in KDBase.h.  You can OR any of these flags
  129.         together.  There are no restrictions on which flags can be or'd with
  130.         others.
  131.  
  132.         The 'extras' is a struct ExtraData (as defined in KDBase.h).
  133.  
  134.  
  135.         struct ExtraData {
  136.             struct Image *UpArrow;          /* replacement image for Up Arrow */
  137.             struct Image *DnArrow;          /* replacement image for Down Arrow */
  138.             struct Image *DiskNormal;       /* replacement image for Disks */
  139.             struct Image *DiskSelected;     /* replacement select image for Disks */
  140.             struct Image *SizeStrip;        /* replacement image for Size gadgets */
  141.             UBYTE        *oktext;           /* text to be used as OK text */
  142.             UBYTE        *canceltext;       /* text to be used as CANCEL text */
  143.             USHORT       LeftEdge,TopEdge,Width,Height;
  144.             struct TextFont *NewFont;       /* New Font to use instead of Topaz 8 */
  145.             };
  146.  
  147.         You can request a specific LeftEdge, TopEdge, Width, and Height
  148.         by giving a non-zero value in any of the above arguments.  However,
  149.         it is recommended that you do not.  The requester will attempt to
  150.         come back up where it was the last time if you don't give it the
  151.         FR_AUTOSIZE and/or FR_AUTOPOSITION flags.  The default values are:
  152.  
  153.             LeftEdge    120
  154.             TopEdge      20
  155.             Width       400
  156.             Height      152
  157.  
  158.         'oktext' is the text that will be shown in the 'OK' gadget.  This
  159.         should be something like "Load" or "Save" or whatever.  The string
  160.         must not be longer than 7 characters or it will be truncated.  Make
  161.         sure that you set the FR_OKTEXT as described above.
  162.  
  163.         'canceltext' is the text that will be shown in the 'Cancel' gadget.
  164.         This should be something like "No!" or whatever.  The string
  165.         must not be longer than 7 characters or it will be truncated.  Make
  166.         sure that you set the FR_CANCELTEXT as described above.
  167.  
  168. RESULT
  169.  
  170.         directory   -   selected path
  171.         filename    -   selected file
  172.         pattern     -   last pattern used
  173.         result      -   1 = success, 0 = requester cancelled or failed.
  174.  
  175.         Note:   UBYTE directory must be least UBYTE [128] in size.
  176.                 and filename and pattern, [32].
  177.  
  178.                 e.g.
  179.  
  180.                 UBYTE directory[128];
  181.                 UBYTE filename[32];
  182.                 UBYTE pattern[32];
  183.  
  184.                 Also, make sure that they are either initialized with
  185.                 default values, or zero'd out.
  186.  
  187. BUGS
  188.  
  189.         None.
  190.  
  191. EXAMPLE
  192.  
  193.         See the file test.c for a detailed example.
  194.  
  195. ------------------------------------------------------------------------------
  196. kd_freq.library/Path
  197.  
  198. NAME
  199.  
  200.         Path - expand a file name to its full path.
  201.  
  202. SYNOPSIS
  203.  
  204.         Path(filename);
  205.  
  206.         UBYTE *filename;
  207.  
  208.  
  209. FUNCTION
  210.  
  211.         Accepts a string that a valid AmigaDOS file or directory name and
  212.         expands it to the full path leading to the file/directory name.
  213.  
  214. RESULT
  215.  
  216.         filename    -   full path 
  217.  
  218.         Note:   UBYTE *filename must be least UBYTE [128] in size.
  219.  
  220.                 e.g.    UBYTE filename[128];
  221.  
  222.         The string is terminated with either a / or a : depending on whether
  223.         it is a valid directory or device.
  224.  
  225.         If the filename is not a valid file name, then 'filename' is truncated
  226.         to 0 length;
  227.  
  228.  
  229. BUGS
  230.  
  231.         None.
  232.  
  233.  
  234. EXAMPLE
  235.  
  236.         UBYTE filename[128] = "dh0:";
  237.  
  238.         Path(filename);
  239.  
  240. ------------------------------------------------------------------------------
  241. kd_freq.library/PatMatch
  242.  
  243. NAME
  244.  
  245.         PatMatch - do AmigaDOS style wild card filename pattern matching.
  246.  
  247. SYNOPSIS
  248.  
  249.         result = PatMatch(pattern,filename);
  250.  
  251.         LONG  result
  252.         UBYTE *pattern;
  253.         UBYTE *filename;
  254.  
  255.  
  256. FUNCTION
  257.  
  258.         Accepts a string that is a valid AmigaDOS file name (filename) and
  259.         a valid AmigaDOS wild card pattern and tells you whether the
  260.         filename matches the pattern or not.
  261.  
  262.         Supported wildcards in pattern:
  263.  
  264.             1.  Standard AmigaDOS Wildcards:
  265.             --------------------------------
  266.  
  267.             ?   Matches any single character
  268.             #p  Match any number of occurences of the pattern p
  269.             %   Matches the null string
  270.             ()  Make a group of characters into a single pattern
  271.             |   The OR operator
  272.             '   Disable wildcard interpretation of next character
  273.                 (unless it is an extended wildcard as shown below.)
  274.  
  275.             2.  Extended Wildcards:
  276.             -----------------------
  277.  
  278.             These are wildcards not supported by the standard AmigaDOS
  279.             convention, but expand it to make it more versatile.
  280.  
  281.             'd  Matches any single digit.  (0 to 9)
  282.             'a  Matches any single alpha character. (a to z)
  283.             'n  Matches any single alphanumeric character.
  284.  
  285.         For examples of standard wildcard usage, look up any AmigaDOS
  286.         tutorial book.
  287.  
  288.         Examples of extended wildcards:
  289.  
  290.         Pattern     Matching possibilities
  291.         -------     ----------------------
  292.         test'n      test0, test1, test9, testa, testA, testz, testZ
  293.         test'd      test0, test1, test9
  294.         test'a      testa, testA, testz, testZ
  295.         test 'd     test 1, test 2, test 9
  296.         test#'d     test1, test100, test10234
  297.         #'a#'d      a1, ab12, abc1, abc123, adks34234
  298.                     (matches any string with some or no alpha characters,
  299.                     then some or no digits.)
  300.         #'a'd#'d.c  a1.c, a203.c, 100.c, 1.c, adsdfs931234.c
  301.                     (matches any string that starts with some of no alpha
  302.                     characters, then at least 1 or more digits, and ends
  303.                     with .c)
  304.  
  305. RESULT
  306.  
  307.         result = -1     Syntax error in wildcard pattern.
  308.         result =  0     Filename did not match pattern.
  309.         result =  1     Filename matched pattern.
  310.  
  311. BUGS
  312.  
  313.         None.
  314.  
  315.  
  316. EXAMPLE
  317.  
  318.         LONG result;
  319.  
  320.         result = PatMatch("#?.c","test.c");
  321.  
  322.         This will result in:  result == 1
  323.  
  324. ------------------------------------------------------------------------------
  325. If you have any trouble getting any call to work, don't hesitate to email me
  326. on Compuserve 75166,2531 or leave me a message in the AmigaTech forum on CIS.
  327. ------------------------------------------------------------------------------
  328.                   Copyright 1990  Khalid Aldoseri.
  329.                          16 January 1990.
  330. ------------------------------------------------------------------------------
  331.  
  332.